<ui:composition template="/WEB-INF/templates/showcase.xhtml"
	xmlns="http://www.w3.org/1999/xhtml"
	xmlns:f="http://java.sun.com/jsf/core"
	xmlns:h="http://java.sun.com/jsf/html"
	xmlns:ui="http://java.sun.com/jsf/facelets"
	xmlns:o="http://omnifaces.org/ui"
>
	<ui:define name="description">
		<p>
			This filter will set the request body character encoding when not already set by the client. Even though
			JSF2/Facelets uses by default UTF-8 everywhere, which is the best charset choice these days, JSF2/Facelets might
			fail to set it to UTF-8 when something else has set it to a different value before JSF2/Facelets gets the chance to
			set it during the restore view phase. PrimeFaces 3.x for example is known to do that. During ajax requests, it will
			call <code>ExternalContext#getRequestParameterMap()</code> inside <code>PartialViewContext#isAjaxRequest()</code> right before
			building/restoring the view, which will implicitly set the request body character encoding to the server-default
			value, which is not UTF-8 per se.
		</p>
		
		<h3>Installation</h3>
		<p>
			To get this filter to run, map it as follows in <code>web.xml</code>:
		</p>
		<pre class="prettyprint"><code class="lang-xml">
&lt;filter&gt;
    &lt;filter-name&gt;characterEncodingFilter&lt;/filter-name&gt;
    &lt;filter-class&gt;org.omnifaces.filter.CharacterEncodingFilter&lt;/filter-class&gt;
&lt;/filter&gt;
&lt;filter-mapping&gt;
    &lt;filter-name&gt;characterEncodingFilter&lt;/filter-name&gt;
    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;
		</code></pre>

		<h3>Configuration (optional)</h3>
		<p>
			As JSF2/Facelets uses by default UTF-8 everywhere, the default charset is also set to UTF-8. When really
			necessary for some reason, then it can be overridden by specifying the <code>encoding</code> initialization
			parameter in the <code>&lt;filter&gt;</code> element as follows:
		</p>
		<pre class="prettyprint"><code class="lang-xml">
&lt;init-param&gt;
    &lt;description&gt;
        The character encoding which is to be used to parse the HTTP request body. Defaults to UTF-8.
    &lt;/description&gt;
    &lt;param-name&gt;encoding&lt;/param-name&gt;
    &lt;param-value&gt;ISO-8859-1&lt;/param-value&gt;
&lt;/init-param&gt;
		</code></pre>
		<p>
			Please note that this only affects HTTP POST requests, not HTTP GET requests. For HTTP GET requests, you should
			be specifying the charset at servletcontainer level (e.g. <code>&lt;Context URIEncoding="UTF-8"&gt;</code> in Tomcat,
			or <code>&lt;parameter-encoding default-charset="UTF-8"&gt;</code> in Glassfish). Also note that this doesn't affect
			HTTP responses in any way. For HTTP responses, you should be specifying the charset in
			<code>&lt;f:view encoding&gt;</code>, which also already defaults to UTF-8 by the way.
		</p>

		<h3>Demo</h3>
		<p>
			The <code>CharacterEncodingFilter</code> is also 
			<a href="http://code.google.com/p/omnifaces-showcase/source/browse/WebContent/WEB-INF/web.xml">configured</a>
			on this showcase application. You can see it by special characters being properly dealt in POST forms throughout
			the showcase application and by the presence of the filter in stacktraces of showcase pages demonstrating some exceptions.
		</p>			
	</ui:define>		
</ui:composition>